home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 July: Mac OS SDK / Dev.CD Jul 96 SDK / Dev.CD Jul 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc Development Framework / Documentation / Engineering Notes / Data Interchange / Promises < prev   
Encoding:
Text File  |  1996-04-26  |  4.7 KB  |  140 lines  |  [TEXT/ttxt]
  1. OpenDoc
  2. Development
  3. Framework
  4.                                                                                                                                                                                                  
  5. Promises 
  6. ODF Release 1                                                                                                                                                                          
  7.  
  8.  
  9. Table of Contents
  10. -------------------
  11. • Introduction
  12. • Basic Steps
  13. • Boilerplate Code
  14. • Keeping Track of Promised Data
  15.  
  16.  
  17. Introduction
  18.  
  19. Support for promises has been made more general in ODF Release 1. It is now easier to promise multiple data types and to use promises for linking. This document outlines the basic steps you need to do to implement promises, and provides some boilerplate code you can copy and adapt to your part. 
  20.  
  21.  
  22. Basic Steps
  23.  
  24. 1) Subclass FW_CPromise
  25.     Override FulfillPromise
  26. 2) In the Externalize method of your Content class:
  27.     Instantiate a promise
  28.     Call promise->Promise(ev, …) for every data type you support
  29.  
  30. For an example of promises in the sample parts, see the CDrawSelectionPromise class and the method CDrawSelectionContent::Externalize in ODFDraw.
  31.  
  32. The example code in the next section assumes the existence of the following Content classes:
  33.     CPromisedContent - designates promised data
  34.     CSelectedContent - designates selected data
  35.     CPublishedContent - designates published data (the source of a link)
  36.  
  37.  
  38. Boilerplate Code
  39.  
  40. 1) Subclass FW_CPromise
  41.  
  42. class CMyPromise : public FW_CPromise
  43. {
  44. public:
  45.     CMyPromise(Environment* ev, 
  46.         FW_EStorageKinds storageKind, 
  47.         FW_CCloneInfo* cloneInfo, 
  48.         CPromisedContent* promisedContent);
  49.     virtual ~CMyPromise();
  50.  
  51.     virtual void FulfillPromise(Environment* ev,
  52.         ODStorageUnitView* promiseSUView,
  53.         ODPropertyName propertyName,
  54.         ODValueType valueType,
  55.         FW_CCloneInfo* cloneInfo);
  56.  
  57. private:
  58.     CPromisedContent* fPromisedContent;
  59. };
  60.  
  61. CMyPromise::CMyPromise(Environment* ev, 
  62.         FW_EStorageKinds storageKind, 
  63.         FW_CCloneInfo* cloneInfo, 
  64.         CPromisedContent* promisedContent)
  65. :    FW_CPromise(ev, storageKind, cloneInfo),
  66.     fPromisedContent(promisedContent)
  67. {
  68.     // Mark content as promised (part-specific)
  69. }
  70.  
  71. CMyPromise::~CMyPromise() 
  72. {
  73.     // Unmark promised content (part-specific)
  74.  
  75.     delete fPromisedContent;
  76. }
  77.  
  78. void CMyPromise::FulfillPromise(Environment* ev,
  79.         ODStorageUnitView* promiseSUView,
  80.         ODPropertyName propertyName,
  81.         ODValueType valueType,
  82.         FW_CCloneInfo* cloneInfo)
  83. {
  84.     // Check the value type and write only that type to the storage unit
  85.     if (FW_PrimitiveStringEqual(valueType, kMyPartKind))
  86.     {
  87.         fPromisedContent->Externalize(ev, promiseSUView->GetStorageUnit(ev), GetStorageKind(ev), cloneInfo);
  88.     }
  89.     else if (FW_PrimitiveStringEqual(valueType, kSomeDataType))
  90.     {
  91.         // write the data type to the storage unit
  92.     }
  93. }
  94.  
  95. 2) Promise the data 
  96.  
  97. When copying or dragging data, use your selection’s content object:
  98.  
  99. void CSelectionContent::Externalize(Environment* ev,
  100.         ODStorageUnit* storageUnit, 
  101.         FW_EStorageKinds storageKind,
  102.         FW_CCloneInfo* cloneInfo)
  103. {
  104.     // ----- Create a content object for the promised data -----
  105.     CPromisedContent* promisedContent = FW_NEW(CPromisedContent, (ev, fMyPart, this));
  106.  
  107.     // ----- Create a promise object -----
  108.     CMyPromise* promise = new CMyPromise(ev, storageKind, cloneInfo, promisedContent);
  109.  
  110.     // ----- Promise all the data types I support -----
  111.     promise->Promise(ev, storageUnit, kODPropContents, GetPart(ev)->GetPartKind(ev));
  112.     promise->Promise(ev, storageUnit, kODPropContents, kSomeDataType);
  113. }
  114.  
  115. When using promises for linking, use your link source’s content object:
  116.  
  117. void CPublishedContent::Externalize(Environment* ev,
  118.         ODStorageUnit* storageUnit, 
  119.         FW_EStorageKinds storageKind,
  120.         FW_CCloneInfo* cloneInfo)
  121. {
  122.     // ----- Create a content object for the promised data -----
  123.     CPromisedContent* promisedContent = FW_NEW(CPromisedContent, (ev, fMyPart, this));
  124.  
  125.     // ----- Create a promise object -----
  126.     CMyPromise* promise = new CMyPromise(ev, storageKind, cloneInfo, promisedContent);
  127.  
  128.     // ----- Promise all the data types I support -----
  129.     promise->Promise(ev, storageUnit, kODPropContents, GetPart(ev)->GetPartKind(ev));
  130.     promise->Promise(ev, storageUnit, kODPropContents, kSomeDataType);
  131. }
  132.  
  133.  
  134. Keeping Track of Promised Data
  135.  
  136. The OpenDoc guidelines say that when a promise is fulfilled you must supply the source content that was selected at the time the promise was written. This means that your part needs to keep track of which data is promised. When promised data is about to be changed or deleted, you need to either fulfill the promise or save the unchanged data for later fulfillment. Sorry, folks! That’s the way it is.
  137.  
  138.  
  139. © 1993 - 1996 Apple Computer, Inc. All rights reserved.
  140. Apple, the Apple Logo, Macintosh, and OpenDoc are trademarks of Apple Computer, Inc., registered in the United States and other countries.